.TH std::from_chars 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::from_chars \- std::from_chars

.SH Synopsis
   Defined in header <charconv>
   std::from_chars_result

       from_chars( const char* first, const char* last,     \fB(1)\fP \fI(since C++17)\fP
                                                                (constexpr since C++23)
                   /* integer-type */& value, int base = 10
   );
   std::from_chars_result

       from_chars( const char* first, const char* last,
                   /* floating-point-type */& value,        \fB(2)\fP \fI(since C++17)\fP

                   std::chars_format fmt =
   std::chars_format::general );

   Analyzes the character sequence [first, last) for a pattern described below. If no
   characters match the pattern or if the value obtained by parsing the matched
   characters is not representable in the type of value, value is unmodified, otherwise
   the characters matching the pattern are interpreted as a text representation of an
   arithmetic value, which is stored in value.

   1) Integer parsers: Expects the pattern identical to the one used by std::strtol in
   the default ("C") locale and the given non-zero numeric base, except that
     * "0x" or "0X" prefixes are not recognized if base is 16
     * only the minus sign is recognized (not the plus sign), and only for signed
       integer types of value
     * leading whitespace is not ignored.
   The library provides overloads for all
   cv-unqualified
   (since C++23) signed and unsigned integer types and char as the referenced type of
   the parameter value.
   2) Floating-point parsers: Expects the pattern identical to the one used by
   std::strtod in the default ("C") locale, except that
     * the plus sign is not recognized outside of the exponent (only the minus sign is
       permitted at the beginning)
     * if fmt has std::chars_format::scientific set but not std::chars_format::fixed,
       the exponent part is required (otherwise it is optional)
     * if fmt has std::chars_format::fixed set but not std::chars_format::scientific,
       the optional exponent is not permitted
     * if fmt is std::chars_format::hex, the prefix "0x" or "0X" is not permitted (the
       string "0x123" parses as the value "0" with unparsed remainder "x123")
     * leading whitespace is not ignored.
   In any case, the resulting value is one of at most two floating-point values closest
   to the value of the string matching the pattern, after rounding according to
   std::round_to_nearest.
   The library provides overloads for all cv-unqualified
   standard
   (until C++23) floating-point types as the referenced type of the parameter value.

.SH Parameters

   first, last - valid character range to parse
   value       - the out-parameter where the parsed value is stored if successful
   base        - integer base to use: a value between 2 and 36 (inclusive).
   fmt         - floating-point formatting to use, a bitmask of type std::chars_format

.SH Return value

   On success, returns a value of type std::from_chars_result such that ptr points at
   the first character not matching the pattern, or has the value equal to last if all
   characters match and ec is value-initialized.

   If there is no pattern match, returns a value of type std::from_chars_result such
   that ptr equals first and ec equals std::errc::invalid_argument. value is
   unmodified.

   If the pattern was matched, but the parsed value is not in the range representable
   by the type of value, returns value of type std::from_chars_result such that ec
   equals std::errc::result_out_of_range and ptr points at the first character not
   matching the pattern. value is unmodified.

.SH Exceptions

   Throws nothing.

.SH Notes

   Unlike other parsing functions in C++ and C libraries, std::from_chars is
   locale-independent, non-allocating, and non-throwing. Only a small subset of parsing
   policies used by other libraries (such as std::sscanf) is provided. This is intended
   to allow the fastest possible implementation that is useful in common
   high-throughput contexts such as text-based interchange (JSON or XML).

   The guarantee that std::from_chars can recover every floating-point value formatted
   by std::to_chars exactly is only provided if both functions are from the same
   implementation.

   A pattern consisting of a sign with no digits following it is treated as pattern
   that did not match anything.

        Feature-test macro       Value    Std                   Feature
                                201611L \fI(C++17)\fP Elementary string conversions
   __cpp_lib_to_chars                           (std::from_chars, std::to_chars)
                                202306L (C++26) Testing for success or failure of
                                                <charconv> functions
                                                Add constexpr modifiers to
   __cpp_lib_constexpr_charconv 202207L (C++23) std::from_chars and std::to_chars
                                                overloads for integral types

.SH Example


// Run this code

 #include <cassert>
 #include <charconv>
 #include <iomanip>
 #include <iostream>
 #include <optional>
 #include <string_view>
 #include <system_error>

 int main()
 {
     for (std::string_view const str : {"1234", "15 foo", "bar", " 42", "5000000000"})
     {
         std::cout << "String: " << std::quoted(str) << ". ";
         int result{};
         auto [ptr, ec] = std::from_chars(str.data(), str.data() + str.size(), result);

         if (ec == std::errc())
             std::cout << "Result: " << result << ", ptr -> " << std::quoted(ptr) << '\\n';
         else if (ec == std::errc::invalid_argument)
             std::cout << "This is not a number.\\n";
         else if (ec == std::errc::result_out_of_range)
             std::cout << "This number is larger than an int.\\n";
     }

     // C++23's constexpr from_char demo / C++26's operator bool() demo:
     auto to_int = [](std::string_view s) -> std::optional<int>
     {
         int value{};
 #if __cpp_lib_to_chars >= 202306L
         if (std::from_chars(s.data(), s.data() + s.size(), value))
 #else
         if (std::from_chars(s.data(), s.data() + s.size(), value).ec == std::errc{})
 #endif
             return value;
         else
             return std::nullopt;
     };

     assert(to_int("42") == 42);
     assert(to_int("foo") == std::nullopt);
 #if __cpp_lib_constexpr_charconv and __cpp_lib_optional >= 202106
     static_assert(to_int("42") == 42);
     static_assert(to_int("foo") == std::nullopt);
 #endif
 }

.SH Output:

 String: "1234". Result: 1234, ptr -> ""
 String: "15 foo". Result: 15, ptr -> " foo"
 String: "bar". This is not a number.
 String: " 42". This is not a number.
 String: "5000000000". This number is larger than an int.

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR    Applied to          Behavior as published              Correct behavior
   LWG 2955 C++17      this function was in <utility> and used  moved to <charconv> and
                       std::error_code                          uses std::errc
   LWG 3373 C++17      std::from_chars_result might have        additional members are
                       additional members                       prohibited

.SH See also

   from_chars_result the return type of std::from_chars
   \fI(C++17)\fP           \fI(class)\fP
   to_chars          converts an integer or floating-point value to a character
   \fI(C++17)\fP           sequence
                     \fI(function)\fP
   stoi
   stol
   stoll             converts a string to a signed integer
   \fI(C++11)\fP           \fI(function)\fP
   \fI(C++11)\fP
   \fI(C++11)\fP
   stof
   stod
   stold             converts a string to a floating point value
   \fI(C++11)\fP           \fI(function)\fP
   \fI(C++11)\fP
   \fI(C++11)\fP
   strtol            converts a byte string to an integer value
   strtoll           \fI(function)\fP
   \fI(C++11)\fP
   strtof            converts a byte string to a floating-point value
   strtod            \fI(function)\fP
   strtold
   scanf             reads formatted input from stdin, a file stream or a buffer
   fscanf            \fI(function)\fP
   sscanf
                     extracts formatted data
   operator>>        \fI(public member function of std::basic_istream<CharT,Traits>)\fP

